home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 3: CDPD 3
/
Almathera Ten on Ten - Disc 3: CDPD3.iso
/
scope
/
151-175
/
scopedisk168
/
dclock
/
dclock.doc
< prev
next >
Wrap
Text File
|
1995-03-19
|
31KB
|
582 lines
============================ DClock v1.29 ============================
======================== A Dumb Clock Utility ========================
======================================================================
========================= IMPORTANT NOTICE ===========================
======================================================================
Due to an important change in the handler <-> main process
communication structure 'DClock' revisions older than 1.7 are
incompatible with this release. Delete the older files and terminate
the clock process before you install the 1.29 update first!
Programmers: starting with v1.12 the DSeg port structure has changed.
To make future expansion easier and to avoid collisions with custom
'DClock' versions ten longwords have been reserved at the bottom of
the structure.
============================ BACKGROUND ==============================
======================================================================
Who cares for clock utilities, really, who does? Well, I do. I
needed one, but couldn't find anything suitable. The standard
Workbench clock was a bit too big, Mclk slowed down system
performance, TUC had far too many features (including occasional
disk-trashing), RSLClock was too large, so was MachII and DMouse
intentionally didn't have any clock display. So, what was I up to do?
Right, I programmed my very special creation, short, sweet and
functional.
============================= FEATURES ===============================
======================================================================
Since I have already cooked out my custom version of DMouse I didn't
need any additional Mouse accelerator, so this one didn't get into it.
What I needed were Date (including weekday) and Time.
The most important question was: where to place the display?
Since I have already tested mouse pointer clocks and my home brewn
MouseClock program which features two sprites hovering at the right
hand side of the mouse pointer, the answer could only be: put it on
the Workbench screen.
Remembering my experiences with ReadySoft's A-Max Apple
MacIntosh Emulator the time display found its way to the right hand
side of the Workbench title bar. The time string is updated each
second.
'DClock' and 'DClock-Handler' need arp.library v39.1 and can
be made resident via the 'ARes' command. If you wish to use the
'DClock' ARexx interface, rexxhost.library v34.9 or above is required.
Mclk uses about 10% of CPU time and about 16000 bytes of
memory (that's almost as much as the standard Workbench clock
consumes), MachII uses 4% of CPU time and 32000 bytes. 'DClock' only
consumes between 1% and 5% of CPU time and requires about 36000 bytes
of memory.
=========================== INSTALLATION =============================
======================================================================
Place 'DClock-Handler' in L:, 'DClock' in C: or SYS:, arp.library in
LIBS:, type "DClock" to install, "DClock quit" to remove. Easy, isn't
it?
============================== EXTRAS ================================
======================================================================
'DClock' still isn't a pure clock utility. I used to install a
program called DisplayBeep in my Startup-Sequence script. This
program spawned a process which replaced the DisplayBeep() function
with a substitute not only to flash the display but also to beep
audibly. To save some memory the code of DisplayBeep.c has been
incorporated into 'DClock-Handler.c'. I also added the Click.c code I
had written back in October. Somebody asked me to add an alarm-clock
function which took me two hours to program.
=============================== USAGE ================================
======================================================================
To start simply type "DClock" (followed by none or more options) and
press return. The main process will be "pulled up" almost instantly.
Note: if ANYTHING goes wrong at this stage, 'DClock' will stop at the
point where "Installing DClock, " appears and nothing else happens
(the handler process has probably died). 'DClock' will wait for ever
unless CTRL-C is pressed. 'DClock' will shut down and issue an error
message.
Now for the command line options. 'DClock' knows and handles the
following:
QUIT .................. Terminates the handler process and removes all
loaded data.
INFO .................. Gives some information on the current 'DClock'
revision.
VERSION ............... Displays the current revision number and
creation date of 'DClock'.
QUIET ................. Suppresses all those neat information messages
which are issued each time an option is
selected.
REFRESH ............... Will reposition the 'DClock' display (vScreen
users: after the screen size has been changed
use this option to move the display).
READCLOCK ............. Similar to the 'SetClock' command, 'DClock'
will read the time from the builtin real time
clock chip and adjust the system time
accordingly. Note: 'DClock' will only read
the information and cannot be used to adjust
the battery backed up time (such as 'SetClock
save'); so do not delete the 'SetClock'
command!
BEEP ON/OFF ........... 'DClock' uses a modified DisplayBeep() routine
which lets the usual display flash (e.g.
after the CTRL-G signal) produce a brief beep
as well as a flash. The beep can be turned
off this way (default is on).
CLICK ON/OFF .......... Each time a key is pressed a keyboard click is
produced (very similar to the high quality
style IBM-PC® keyboards). This feature can be
turned off this way (default is off).
SPEECH ON/OFF.......... 'DClock' will tell you the time using the
builtin narrator.device. This feature can be
turned off and on using this switch.
(default is off)
HOUR ON/OFF ........... The 'hour' feature will give a brief 'beep'
signal each full hour. I suppose this could
be a lot funnier if the beep would be replaced
by the chime of the Clock Tower of The Houses
of Parliament ('Big Ben'). Any sampled sound
donations are welcome. (default is off)
SECONDS ON/OFF ........ 'DClock' displays the current time including
minutes and seconds. The second display can
be turned off via keyboard or with this
option. (default is on)
SETENV ON/OFF.......... Will write the day, date & time to Manx-type
environment variables (DAY, DATE & TIME).
This feature can be turned on and off.
(default is off)
COUNTDOWN #/SHOW ...... This is how 'DClock' can help you to make tea:
set the timeout to, say 300 (= 5 minutes * 60
seconds) while your Earl Grey tea is drawing.
'DClock'will ring the bell after five minutes.
'DClock COUNTDOWN SHOW' will display the
number of seconds to elapse before the
countdown clock rings.
SOUND <Name>/OFF ...... I don't know if this is useful for anyone, but
it may be good for a laugh. The default hour
chime produces a simple beep signal. This
option will load any IFF-8SVX-sound and play
it each time it is required. Selecting 'OFF'
as the argument to this option will reset to
the default beep. (default is - of course -
the default beep)
TEXTCOLOUR # .......... The colour in which the 'DClock' time and
memory display will appear can be adjusted
this way. (default is 0)
BACKCOLOUR # .......... Same as above, but controls the background
colour. (default is 1)
CLICKVOLUME # ......... The volume of the keyboard click can be
adjusted between 0 and 64. (default is 64)
PRIORITY # ............ This determines the handler process priority.
Any number between -128 and 127 will do.
(default is 5)
PAGE # ................ Selects one of the four (five) display pages
as the startup page. (default is page 0)
ALARM ON/OFF/SHOW ..... The alarm clock function is controlled by this
function. It can be turned off and on. SHOW
displays the currently selected alarm time.
(default is off)
ALARMTIME HH:MM:SS .... The alarm time is adjusted via this option,
note that the alarm itself must be turned on
separately. (default time is 12:00:00)
Workbench users: 'DClock' can be started from Workbench! The
following tooltype entries correspond to the approriate CLI options
and have to appear in capital letters:
BEEP, CLICK, CLICKVOLUME, PRIORITY, TEXTCOLOUR, BACKCOLOUR, ALARM,
ALARMTIME, SETENV, COUNTDOWN, HOUR, SECONDS, SOUND, PAGE, SPEECH,
READTIME
The expected arguments are the same as with the CLI options.
========================== DCLOCK AND AREXX ==========================
======================================================================
Important notice: the DClock<->ARexx interface will only work if
rexxhost.library v34.9 or above is present in your system!
Interfacing to 'DClock' from ARexx is fairly easy. An example script
could look like this:
/* A simple DClock<->ARexx demonstration. */
/* We want results to be returned from 'DClock'. */
options results
/* Take 'DClock' as the host address for the following
* commands.
*/
address dclock
/* Do something sensible, first ask 'DClock' to return its
* version number.
*/
status version
say 'You are using DClock' result
/* We'll turn on the keyboard click. */
click on
/* And we'll set the display colours. */
textcolour 3
backcolour 2
/* Ask 'DClock' to tell us the time. */
telltime
/* That's all, read on! */
The 'DClock' ARexx interface knows all commands which can be set from
CLI using the 'DClock' main program. The only difference is that
commands displaying information such as 'DClock ALARM SHOW' will leave
a result in the ARexx 'result' variable. These results are obtained
through the 'status' command, not through the setting commands
themselves. 'status version' will return the current 'DClock'
version, 'status alarm' will return 'off' if alarm is disabled, 'on'
if alarm is enabled. The 'status' command knows the following
keywords:
BEEP, CLICK, CLICKVOLUME, PRIORITY, TEXTCOLOUR, BACKCOLOUR, ALARM,
ALARMTIME, SETENV, VERSION, COUNTDOWN, HOUR, SECONDS, SOUND, PAGE,
SPEECH, LINE
Note: 'LINE' will report 'OFF' if your Amiga computer is currently
offline and 'ON' if a carrier signal is detected.
If 'status' doesn't recognize a keyword or if you don't supply one, it
will return a string of the following format:
BEEP ON CLICK OFF CLICKVOLUME 64 PRIORITY 5 TEXTCOLOUR 0 BACKCOLOUR 5
ALARM OFF ALARMTIME 12:00:00 SETENV OFF VERSION 20 COUNTDOWN 0 HOUR
OFF SECONDS OFF SOUND OFF PAGE 0 SPEECH OFF LINE OFF
The ARexx interface itself isn't very powerful yet, since it was
designed to simplify the rendezvous with DClockMenu.rexx. It is quite
DClock-specific, no other program will profit from interfacing to
'DClock'. It's up to you to decide what 'DClock' will be good for.
The ARexx interface will recognize a request to tell the
current time. The approriate command is called "TELLTIME". Note that
this function will still work if speech is turned off globally.
========================= DCLOCK AND HOTKEYS =========================
======================================================================
The 'DClock' display is controlled by two hot-keys: LEFT-AMIGA+HELP
and LEFT-AMIGA+DEL. The help-key cycles through five and a half (what
does he mean by 'a half'?) different displays: time and date,
graphical memory display, numerical memory display and online timer.
The del-key toggles whether the time display includes seconds or not.
If a countdown is currently running it will be displayed on the fifth
page (which you know can be flipped with LEFT-AMIGA+HELP). If speech
is enabled, 'DClock' will tell you the current time if you press
LEFT-ALTERNATE+HELP. Note that if speech has just been disabled,
pressing these keys will deallocate the speech task freeing additional
memory. If speech is turned on again, or the TELLTIME command comes
in from ARexx, the speech server will be reinitialized.
======================== FUTURE ENHANCEMENTS =========================
======================================================================
Since starting with this revision the hour chime sound can be loaded
externally, the next logical step would be to approach keyboard click,
displaybeep and alarm clock in a similar way. To be frank: I don't
see the sense behind it. If you do, try to add it on your own (I
always said that custom 'DClock' versions are generally appreciated)
or try to convince me to add this feature in a future revision.
In my opinion - which is shared by the majority of 'DClock'
users who have contacted me yet - 'DClock' has reached the point where
each new feature has to be weighed carefully against size and
usefulness. If you want 'DClock' to have new functions (e.g. to
start script files at fixed points of time or to use multiple alarm
times) think twice before requesting them.
============================== PROBLEMS ==============================
======================================================================
Selecting CLICK ON together with BEEP ON can cause problems if ConMan
output has been halted with ^S. It is quite likely that click and
beep will lock each other and the Amiga crashes. I haven't found a
solution to this yet.
============================== CREDITS ===============================
======================================================================
Credits go to ARP Programmers for the most recent version of ARP, to
Matt Dillon for DMouse, to Mike Oldfield & Peter Norman for the
keyboard click, to Mason/Waters/Wright/Gilmour/Parsons for the alarm
clock sound, to John Hodgson for the beep, to Thad Floryan for his
date conversion routines and to Justin V. McCormick for the very
basic string formatting code.
A special mention must also go to Bill Hawes, author of ARexx,
and to the authors of CygnusEd Professional 2 (Bruce Dawson & Colin
Fox) whose programs both controlled the compiler runs.
The DClockMenu.rexx code was created by Stefan Sticht who also
is responsible for a good lot of ideas which have been incorporated
into 'DClock' over the last few months.
================== COPY FEE, AUTHORS REQUEST, ETC. ===================
======================================================================
If you like 'DClock' and wish to contribute any money I urge you to
send at least 10 US$ to...
Amnesty International
P.O. Box 37137
Washington D.C. 20013
I suppose Amnesty International can make better use of the money than
I can. Even the smallest contribution makes sense.
I don't care what happens to 'DClock' and 'DClock-Handler', copy them,
sell them, delete them, they are meant to be PUBLIC-DOMAIN. But don't
'fleece' other users for them. Permission to redistribute the
documentation, the source code and executable files granted as long as
the body of this document is left intact.
-
I have tried to make 'DClock' as flexible as possible. The rendezvous
data is easily to be extended. I encourage you to add whatever
feature you want. I only ask you to send me a copy of your custom
version of 'DClock'. The future of this tool depends on you, spread
the word and also the disk! My address is:
Olaf Barthel, MXM
Brabeckstrasse 35
D-3000 Hannover 71
Federal Republic of Germany
============ REVISION HISTORY (most recent change first) =============
======================================================================
V1.29 Small bug fixed in the speech/rexx server. If the speech
server was started by the rexx server it could accidentally
freeze the rexx server and flag the handler process to exit
(some kind of chain reaction). The speech server would - as
usual - prefer to crash if told to quit. The display beep
would not work correctly. The beep sound has changed (plays a
sine wave instead of a square wave).
V1.28 Finally - the 'TurboBackup v1.0' <-> 'DClock' crash has been
fixed! I cannot ascertain how it came to pass, but the
programs do not lock each other out any more. All files have
been recompiled using Aztec 'C' 5.0b. 'DClock-Handler' now
also uses arp.library (which reduced the size of the
executable file by about 4000 bytes).
V1.27 This release introduces a new useful feature: your
startup-sequence script can be sped up greatly by removing the
'SetClock load' call and by adding the 'Readclock' keyword to
the 'DClock' command line. Starting with this release
'DClock' is able to read and set the system time by taking a
look at the battery backed up clock chip (information on the
registers contained in the chip were lifted from Ralph Babel's
Amiga-Guru Book). The code size went down by almost
2000 bytes for both 'DClock' and 'DClock-Handler'. A small
bug was fixed in the LoadChimeSound routine (the replay rate
was miscalculated). Please note that this revision does not
use any inline library calls. Careful analysis revealed that
parts of my Aztec 5.0a Arp wrapper were broken which could
eventually knock out the the DClock main program. This has
been fixed. The speech server had the unnerving habit of
crashing when flagged to shut down; needless to say, this has
fixed, too.
V1.26 This revision includes some major, major changes; a new date
conversion routine has been incorporated into the handler.
Sometimes the old one miscalculated the date, resulting in
negative date values (blessed are those who were born on the
-1st of January 1978). More important, DClock will adjust
itself *automagically* to the current font used on the
Workbench screen. This is another benefit for A3000 users (if
you don't have an A3000, SetFont by Dave Haynie will do). The
images once displayed in the Full/Empty bar are gone and will
probably never return. Peter Fischer contributed the sampled
sound of 'Big Ben', thanks Peter!
V1.25 For the benefit of A3000 owners 'DClock' will adjust to the
new Kickstart environment. Images are 'remapped' and colours
are swapped to fit the new standard colour palette. The
display is shifted a bit to the right to take advantage of the
additional space available in the Workbench screen title bar.
Minor changes have been made to various parts of the code.
V1.24 Made small changes to support code to cut down code size and
to speed up special code passages. Due to a semicolon behind
an if() check RexxHostBase was always closed regardless if it
was valid or not causing crashes on systems in which
rexxhost.library was not present. The original DisplayBeep
ROM code could accidentally crash the system. To avoid such
collisions I have added back the old VideoBeep/AudioBeep code.
Starting with this release, the keyboard click is by default
disabled.
V1.23 I was asked to add an online timer which took me some time to
create. At first I started playing with hot-keys to start/stop
the timer. After a while I discovered that some CIA or Custom
chip register contains a flag indicating if the serial port is
currently busy. The online timer will start as soon as a
carrier signal is detected, and will stop if the carrier
signal is lost. As a result, the countdown display has been
moved to the fifth display page (the online timer currently
resides on the fourth page). Note that the online timer will
only work with the standard serial.device, the Supra modem
(internal A2000 modem) or the ASDG extra modem are definitely
not supported. I haven't checked how the online timer keeps
up with multiplexed serial signals (I don't have any
multiplexing hardware connected to my serial port). Starting
with this release the DisplayBeep video beep will be handled
by the original ROM code.
V1.22 Discovered that even the Ring() routine used to hang when
terminating the sound using AbortIO. I suppose that there is
something badly wrong with audio.device which should be fixed
as soon as possible (e.g. in Kick2.0). This routine - as
some others do - now rather calls WaitIO than AbortIO. I also
added the speech feature I found missing. If working with
different custom screens you can't always take a look at the
clock display. This feature uses less memory than you might
think, the speech server even gets deallocated if speech is
turned off. And anyway, if they build cuckoo clocks with tea
machines and put together copy programs with builtin Tetris
games, why shouldn't there be a clock utility to tell you the
time?
V1.21 Added PAGE option, rewrote the display beep code (used to do a
Forbid after LockIBase which could result in a deadly
embrace), rewrote the time display routine (used to hang if
seconds were turned off externally). There also was a problem
with the keyboard click/display beep code which caused one
routine stealing the other one's audio channel. As a result
DClock-Handler would lock-up trying to vacate the keyboard
click channel on exit. This has been fixed. There was
another problem with the sound: under certain circumstances
an IORequest would never terminate (as you may know there are
similar problems with serial.device). This has been fixed
using AbortIO followed by a series of GetMsg/ReplyMsg calls.
V1.20 DClock-Handler was extensively rewritten for size and speed.
Andreas Gehrke suggested an option to turn off the seconds in
the time display which I finally added. Added the SOUND
option.
V1.19 The ARexx interface has been partly rewritten to deal with the
result codes correctly. Furthermore I've added an option to
make 'DClock' beep briefly each full hour (this option was
suggested by Stefan Sticht, thanks Stefan!). The command line
option 'DClock ALARM INFO' has changed to 'DClock ALARM SHOW'.
The ringing alarm clock can be cancelled via keyboard now.
V1.18 The countdown option was introduced whilst playing Battle
Squadron and drinking lots of cups of Earl Grey tea. Credits
go to Holger P. Krekel who thought it to be a nice idea to
have a reliable timer for making tea.
V1.17 Finally - it has an ARexx interface and it even makes tea!
Can't say that the ARexx interface has any peculiar function
yet, it really doesn't do very much. But as usual, it's up to
you to expand it. Important: you need rexxhost.library 34.9 or
above to use the ARexx feature.
V1.16 General cleanups for Aztec 5.0 release. Most functions have
been ANSIfied, illegal calling procedures were fixed, as well
as unused variables were removed.
V1.15 Some minor bug fixes, this distribution now also includes the
DClockMenu.rexx macro file written by Stefan Sticht.
V1.14 Fixed some bugs in the alarm clock routine (thanks to Peter
Fischer the clock will break after thirty seconds of constant
ringing), the beep routine (thanks to Stefan Sticht who
discovered that disabling the beep function also killed the
visual beep) and the PopRequest function which could crash if
former front screen/active window had been closed during the
request.
V1.13 Tried to port 'DClock' to Lattice 'C'; well,the attempt didn't
last very long, I will wait for the Aztec 'C' 5.0 compiler
update. Some calling mistakes were traced.
V1.12 I 'ripped' the PopRequest routine from my programmers' library
(mxm.library) and integrated it into the DClock.c code. This
will display real error messages ever so often the Workbench
tool info parsing routine stumbles upon an error. Note also:
I've quit the Electronic Design Hannover team and the
copyright changes to MXM. A note on the code (whoops, it
rhymes!): the pop-up requester part may be incorporated into
any program which has any need of it. If the CED Professional
update had reached us earlier the req.library pop-ups would
have been employed instead of my requesters. It's too late
now, I don't want to change the code any more and anyway:
some of you might think that 30 libraries (that's as much as
there are in my LIBS: drawer) are enough and will prefer to
use the non-library code instead.
V1.11 Wow! The display found its way back to the Workbench title
bar -> with the fastest refresh scheme possible. This is done
via rendering into an invisible RastPort; this image is
transferred to the Workbench bar layer. Now also included:
display will move to the left hand of the screen depth
arrangement gadgets after the REFRESH option is selected.
V1.10 Better Workbench support added (older revision preferred to
crash too often and didn't notice if Workbench was re-opened
after closing the last custom screen). 'DClock' window will
auto-adjust its position to appear at the left hand side of
the screen depth arrangement gadgets (a special gift for
overscanned Workbench screens - merry Christmas, it's the 22nd
of December 1989!).
V1.9 Full Workbench support added (oh boy, I am tired!). I will
try to supply a neat icon to get it working.
V1.8 CloseWBench()/OpenWBench() support available now! 'DClock'
will close its window just in time to allow the Workbench
screen to be closed. It will re-open its window as soon as
the Workbench screen has successfully been re-opened. New for
single-bitplane Workbench (soon to come in Kickstart 1.4):
memory gauge will display a shaded bar instead of an orange
one.
V1.7 Some cosmetical changes, no spectacular work done; well,
except for the small bug fix in the alarm routine (alarm only
worked if time display was active). Docs partly rewritten,
cleaned up some code. Important: added new DSeg entry:
RingBack -> no downward compatibility with older 'DClock'
revisions guaranteed anymore (sorry, but this was absolutely
necessary).
V1.6 Not released.
V1.5 Added a most unnerving alarm clock function: the display
vibrates, a bell is ringing ... what can it be? Probably
'DClock' trying to wake you up.
V1.4 Fixed bug in time signal routine (didn't update if time was
set backwards), added status line information, corrected
exit() calls in 'DClock'.
V1.3 Played around with a taller custom font (saw Kickstart 1.4
alpha 15 and noticed that the Workbench status line became
longer overriding the 'DClock' display). The font didn't get
into it. Added a numerical memory display.
V1.2 Thought of incorporating the code of Click and DisplayBeep
into 'DClock' and added them. Also stumbled upon my old
MemGauge program and added a memory gauge display.
V1.1 Added ARP interface, replaced standard DOS calls with ARP
calls, removed the clock display from the barlayer (always
crashed after a call to CloseWorkBench()), added weekday
conversion and command line options.
V1.0 Simple ('dumb') backdrop clock with date and time display to
be rendered directly into the Workbench bar layer.
*
Do only its possibilities make it an Amiga?
WHERE IS THE MAGIC ???